home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / asmutil / disasm.zip / UASM.DOC < prev    next >
Text File  |  1988-06-03  |  25KB  |  521 lines
  1.                                 UASM.DOC
  2.  
  3.         UASM  (for  Unassembler) consists of five files at this time:
  4.     UASM.DOC,  UASM-JMP.BAS,  UASM-INT.BAS,  UASM-STR.BAS  and  UASM-
  5.     DOS.MAC,  with  the purpose of converting the unassembled listing
  6.     of a .COM file from DEBUG into a .ASM file which can be  modified
  7.     and re-assembled with the Macro assembler.
  8.  
  9.     **************************** NOTICE *****************************
  10.  
  11.        USER SUPPORTED SOFTWARE  (With thanks to Andrew Flugelman)
  12.  
  13.     A limited license is granted to  all  users  of  these  programs,
  14.     to  make  and  distribute  copies  for other users subject to the
  15.     following conditions:
  16.  
  17.        1.  None of  the  notices  or  credits  are  to  be  bypassed,
  18.            altered, or removed.
  19.        2.  The programs are not to be distributed in  modified  form.
  20.            (Users are encouraged to distribute MERGE files.)
  21.        3.  No fee is  to  be  charged  (or  any  other  consideration
  22.            received) for copying or distributing the programs without
  23.            an express written agreement with White Crane Systems.
  24.  
  25.     ***************************************************************
  26.  
  27.                UASM - The White Crane Systems Unassembler
  28.  
  29.         If you are using these program  and  finding  them  of  value
  30.     please  send  a  cash  contribution  to  support their upkeep and
  31.     distribution.  Use the UASM  system  of  programs  to  unassemble
  32.     one average length .COM file, look over the results and calculate
  33.     how many hours this would have taken you  to  produce.   Multiply
  34.     this  by  the  minimum  wage,  contribute that amount and use the
  35.     program free thereafter.  If  that's  too  much  just  send  $20.
  36.     Supporters  will receive free notice of enhancements and updates.
  37.  
  38.         In any case you are encouraged to copy  and  distribute  UASM
  39.     to  your friends provided you do so free of charge and in unmodi-
  40.     fied form.
  41.                              Guy C. Gordon
  42.                           White Crane Systems
  43.                           3194 Friar Tuck Way
  44.                           Doraville, GA 30340
  45.  
  46.                               INTRODUCTION
  47.  
  48.         The strategy used in this system is  to  capture  the  output
  49.     of  DEBUG  and  run  it  through a series of BASIC programs, each
  50.     of which modifies one type of statement in  the  listing,  making
  51.     it  more like an .ASM source file.  This keeps each program short
  52.     and fast, and allows you to look over the  output  at  each  step
  53.     to  make  sure  no mistakes have been entered.  It also makes the
  54.     programs easy to understand and  improve  as  new  steps  can  be
  55.     added  without  interfering  with  the  first steps. Later in its
  56.     development UASM will combine these steps.   I  hope  that  users
  57.     of  these  programs  will  send  me  their improvements so that I
  58.     may add them to future releases.
  59.  
  60.         UASM-JMP takes captured unassembled code  from  DEBUG  (which
  61.     we  will  name  FILE.DB)  and  finds  all addresses referenced by
  62.     the various Jump, Call, and Loop instructions.  These  referenced
  63.     addresses  are  made  into  labels  of the form Lhhhh (where hhhh
  64.     is the hex address).  A  new  file  (FILE.JMP)  is  then  written
  65.     in  the  form  of  assembler  source  code.  All of the addresses
  66.     and hex opcodes in the left two  columns  of  the  DEBUG  listing
  67.     are  left  out.   Referenced  lines  are appropriately labeled as
  68.     Lhhhh:.  In addition, unconditional  program  transfers  such  as
  69.     JMP,  JMPS,  RET  and  IRET have blank lines inserted after them.
  70.     If the next line is not referenced  it  will  be  force  labeled,
  71.     and  a  warning  comment  will be appended.  The line after a RET
  72.     or IRET is most likely the  beginning  of  a  Procedure,  and  is
  73.     preceeded by three blank lines.
  74.  
  75.         UASM-INT  reads  FILE.JMP  and  writes  FILE.INT  in which it
  76.     has added Macro calls and comments explaining the various  Inter-
  77.     rupts.   The  macros,  symbols,  and  comments  are read from the
  78.     file UASM-DOS.MAC.  This file contains a table of  EQUates  which
  79.     define  the  symbols  for  the various DOS function calls and the
  80.     DOSCALL macro.  It is included in FILE.INT by means of an INCLUDE
  81.     directive.
  82.  
  83.         UASM-STR  reads  FILE.INT  and  writes FILE.STR.  Whenever it
  84.     encounters a DOSCALL PRINT$ hhhh it reads  the  string  beginning
  85.     at  hhhh  from  the original .COM file and prints it as a comment
  86.     beside the macro call.  It also generates a  Dhhhh:  DB  'string'
  87.     instruction  at  the  end  of  the  file.  Carriage Returns, Line
  88.     Feeds, TABs and ESCapes are  expressed  as  symbols.   All  other
  89.     non-printing characters are expressed as hex data bytes.  Because
  90.     this will not catch all text strings in the file,  you  are  also
  91.     allowed  to  specify ranges of DEBUG addresses in which  UASM-STR
  92.     is to find all the strings  it  can.   Whenever  the  code  loads
  93.     the  DX  register  with the address of one of these strings, that
  94.     address is converted to a label and the string is  added  to  the
  95.     line as a comment.
  96.  
  97.         From that point on, you must take over and supply the remain-
  98.     ing text strings and variables that are  addressed.   You  should
  99.     heavily  comment  the  code  as  you go through it and change the
  100.     labels that UASM has assigned into more meaningful  names.   This
  101.     is  best done with the global change command in your text editor.
  102.     I also recommend using the Macro CREF program to obtain  a  cross
  103.     reference map of the symbols.
  104.  
  105.         These  programs  are  by  no  means  infallible, and they can
  106.     no more read the programmers' mind than you or  I,  so  you  will
  107.     have  to  check  the output closely.  If you expect to simply run
  108.     UASM and be handed a usable source file you're going to be disap-
  109.     pointed.   On  the other hand, if you've ever tried to understand
  110.     a program from just a DEBUG listing you will be  pleasantly  sur-
  111.     prised.   UASM  will  aid you in studying other programs by doing
  112.     a lot of the dirty work for you,  but  if  you  don't  study  the
  113.     code  you  won't  get  usable  output.   For example an interrupt
  114.     handling subroutine will not  necessarily  be  assigned  a  label
  115.     by  UASM-JMP  since it is not accessed by a Jump but by an inter-
  116.     rupt.  Therefore if you find a DOSCALL SET$INT hhhh in the  UASM-
  117.     INT  output  you  must check to see if the label Lhhhh was gener-
  118.     ated.  If not will have to go back to the DEBUG  output  to  find
  119.     the routine at address hhhh and assign it a label of your own.
  120.  
  121.         At  present,  UASM-INT  only  keeps  track of the AX, AH, AL,
  122.     DX, and DL registers.  Future improvements will  involve  a  more
  123.     complete  (and  much more complicated) DOSCALL macro in the UASM-
  124.     DOS.MAC file and the proper  calling  of  it  by  UASM-INT.   For
  125.     now, keep a close eye on the interrupts.
  126.  
  127.         I  have  been  using  these  programs to unassemble DEBUG.COM
  128.     and COMMAND.COM.  When  I  have  them  sufficiently  commented  I
  129.     will  post them on the BBS's.  At present I use mainly the Multi-
  130.     Link BBS at (404) 252-9438.  It is my hope that  UASM  will  lead
  131.     to a whole library of well commented, "reverse engineered" source
  132.     code for the MS-DOS operating  system  and  utilities.   I  would
  133.     appreciate anyone else working on the same to upload your results
  134.     to the BBS.  Suggestions and improvements  are  welcome.   Please
  135.     post them on the MultiLink BBS or send them directly to:
  136.  
  137.                       Guy C. Gordon
  138.                 White Crane Systems
  139.                 3194 Friar Tuck Way
  140.                 Doraville, GA 30340
  141.                          OPERATING INSTRUCTIONS
  142.                                  -DEBUG-
  143.  
  144.         As an example, we will unassemble a fictitious file, FILE.COM
  145.     A>debug file.com
  146.     -r
  147.     .....CX=1780 ...            ;file length in hex bytes
  148.     -d 100 l 1780